---
title: SAIF.Services.Appworx architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: <owner>
last_reviewed: 2026-08-21
library: SAIF.Services.Appworx
reference_type: package
---

# SAIF.Services.Appworx architecture

`SAIF.Services.Appworx` is a small, single-purpose class library that wraps submission of batch jobs to the Appworx scheduling system via a single Oracle stored procedure, exposed through the SAIF BOF data portal.

## Responsibilities
- Assemble and submit an Appworx batch-job request (module name, requestor, printer, up to 20 string arguments) to the `submit_appworx_job` stored procedure via the SAIF BOF data portal.
- Provide both an instance API (construct, set properties, call `SubmitBatchJob()`) and a shared/static convenience overload that performs construction, argument assignment, and submission in a single call.
- Normalize submission failures into a single `ApplicationException` type so callers see a uniform failure mode regardless of the underlying data-access error.
- Optionally override the target Oracle environment for Appworx submissions in non-production environments via the `inUseWCISDEV1AppworxForAllDevEnv` flag on the shared overload.

## Component boundaries
- `clsRequestAppworxJob` (sole public type): owns the entire responsibility of this library — request-shape assembly and stored-procedure submission. It contains no business-rule engine, no `Criteria` inner class, and does not implement the `IBusinessCriteria` pattern used elsewhere in the SAIF BOF framework; it is a direct data-portal caller rather than a full BOF business object*.
- SAIF BOF Framework boundary: the library depends on `IDataPortalInfo` / `IPortalRequest` / `IDataRequest` (data portal abstraction), `clsMSOracleDataLayer` (Oracle data-layer construction), and `AppGlobal.EnvironmentService` (environment lookup) — all supplied by the referenced `SAIF.BOF.Framework` package family. The internal implementation of the data portal and its Oracle connectivity is outside this library's boundary and was not traced here**.
- Database boundary: the library's only interaction with persistent state is a single outbound stored-procedure call (`submit_appworx_job`); it owns no tables and performs no direct SQL.
- Consumer boundary: `SAIF.Application.Claim.Legal\LegalNet\` (`clsRequestManager.vb`, `clsMailDateManager.vb`, `clsCreateFileManager.vb`) calls the shared `SubmitBatchJob` overload to submit the `LGN0002_LEGALNET_LETTERS` Appworx job for LegalNet letter-request, mailed-date-update, and create-file workflows. `SAIF.Business.Claim.Legal` declares a project reference but no direct source-level usage was confirmed within scanned scope**.

## Interaction model
- **Instance model**: a caller constructs `clsRequestAppworxJob` with an `IDataPortalInfo`, sets `ModuleName`/`Requestor`/`Printer`/`Arg1`–`Arg20`, then calls `SubmitBatchJob()`, which builds an `IPortalRequest`/`IDataRequest` pair and invokes `DPI.ProcessPortalRequest(...)`.
- **Shared/static convenience model**: `clsRequestAppworxJob.SubmitBatchJob(inDPI, inModule, ...)` wraps construction, argument assignment, and submission in one call; this is the pattern used by all observed callers.
- **Environment override**: when the shared overload's `inUseWCISDEV1AppworxForAllDevEnv` flag is `True`, the library bypasses the caller-supplied `IDataPortalInfo` and derives a new one from a fixed `clsMSOracleDataLayer("PRADT", target)`, where `target` is `WCISPROD` in Prod and `WCISDEV1` otherwise (per [BR-APX-003](business-rules.md#br-apx-003-non-production-appworx-target-override)).
- All submission failures are caught and rethrown as `ApplicationException` (per [BR-APX-002](business-rules.md#br-apx-002-submission-failures-are-wrapped-and-rethrown)), presenting a uniform failure contract to callers.

## Design constraints
- No `<ProjectReference>` elements exist in the `.vbproj`; all SAIF framework dependencies are consumed as prebuilt NuGet packages rather than in-repo project references.
- The library targets .NET Framework 4.6.2 and depends on Oracle connectivity (`Oracle.ManagedDataAccess`) registered via `App.config`/`Web.config` `DbProviderFactories` entries.
- Argument capacity is fixed at 20 positional string arguments (`Arg1`–`Arg20`); there is no mechanism for additional or named arguments.
- The library performs no validation of `ModuleName`, `Requestor`, or `Printer` values beyond passing them as fixed-length stored-procedure parameters (30/32/30 characters respectively).
- The `submit_appworx_job` stored procedure body resides in the Oracle database and was not accessible for inline inspection; its internal table interactions are opaque to source-level analysis**.

## Architecture diagram
The following diagram shows the request submission flow from caller through the environment-override decision to the Appworx stored procedure.

```mermaid
flowchart TD
    A["Caller (e.g. LegalNet manager class)"] --> B["clsRequestAppworxJob.SubmitBatchJob (Shared overload)"]
    B --> C{"inUseWCISDEV1AppworxForAllDevEnv = True?"}
    C -->|Yes, Prod env| D["clsMSOracleDataLayer(PRADT, WCISPROD)"]
    C -->|Yes, non-Prod env| E["clsMSOracleDataLayer(PRADT, WCISDEV1)"]
    C -->|No| F["Use caller-supplied IDataPortalInfo"]
    D --> G["New clsRequestAppworxJob(DPI)"]
    E --> G
    F --> G
    G --> H["Set ModuleName, Requestor, Printer, Arg1..Arg20"]
    H --> I["SubmitBatchJob() instance method"]
    I --> J["IDataPortalInfo.ProcessPortalRequest"]
    J --> K["Stored procedure: submit_appworx_job (Oracle)"]
```

## Sequence diagram
The following diagram shows the primary request/response sequence for the shared convenience overload used by all observed callers.

```mermaid
sequenceDiagram
	participant Caller
	participant AppworxJob as clsRequestAppworxJob
	participant DPI as IDataPortalInfo
	participant Oracle as Oracle (submit_appworx_job)
	Caller->>AppworxJob: SubmitBatchJob(inDPI, inModule, inRequestor, inPrinter, args...)
	AppworxJob->>AppworxJob: InitArgs()
	AppworxJob->>AppworxJob: Assign ModuleName, Requestor, Printer, Arg1..Arg20
	AppworxJob->>DPI: ProcessPortalRequest(PortalRequest)
	DPI->>Oracle: Execute submit_appworx_job(inModule, inRequestor, inPrinter, [inArg1..inArg20])
	Oracle-->>DPI: Result / exception
	DPI-->>AppworxJob: Result / exception
	AppworxJob-->>Caller: Return, or ApplicationException on failure
```

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Database tables](database-tables.md)
- [Configuration](configuration.md)
- [SQL catalog](sql/index.md)
- [Stored procedures](procedures/index.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Services.Appworx\clsRequestAppworxJob.vb`
- `SAIF.Services.Appworx\SAIF.Services.Appworx.vbproj`
- `SAIF.Services.Appworx\App.config`
- `SAIF.Services.Appworx\Web.config`
- `SAIF.Services.Appworx\packages.config`